Part 1Create and deploy your first Gatsby site
Now that you've set up your computer with all the tools you'll need, it's time to get started!
In this section, you will go through the process of creating and deploying your first Gatsby site.
What You Will Learn
By the end of this section, you will be able to:
- Create a new Gatsby site.
- Deploy your site using Gatsby Hosting.
Creating a Gatsby site
The Gatsby command line interface (CLI) has a command you can use to create a new Gatsby site:
This command brings up an interactive prompt that will ask you questions about the site you want to build. After you enter the information, the CLI will automatically generate your new Gatsby site based on your answers.
Since this is an introductory workshop, don't add any of the extra integrations yet. You'll add them yourself later on. (But for future projects, know that you can use the CLI to set those features up automatically!)
Something Not Working?
If you're running into trouble using the Gatsby CLI on your machine, you can follow along by forking this CodeSandbox template.
Running your site locally
To run your site locally, you'll first need to change directories in your terminal (with the
cd command) so that you're in the folder that was created for your new site.
There are two ways you can run your site locally. In your terminal, change into the directory for your site, then run one of the following sets of commands:
- Option 1:
- This starts up a local development server. It has some features that make it easier to work on your site. For example, hot reloading will trigger your site to rebuild automatically after you make changes to a file.
- You can see your site in a browser by visiting
- Option 2:
gatsby buildand then
gatsby buildwill create a production-style build of your site and put it in the
gatsby servestarts up a local server that uses the code in
- You can see your site in a browser by visiting
- A prod-style build has more optimizations, but you'll lose some developer-experience features like hot reloading.
In this workshop, you'll use
Setting up a GitHub repo for your site
GitHub is a website that many developers use to back up and share their code online. By uploading your code to GitHub, you'll be able to work on the same codebase from multiple computers. You'll also be able to use Gatsby Cloud to build and host your site.
Each codebase on GitHub is stored in its own repository (also called a "repo", for short). To create a new repository for your blog, click the plus icon in the top-right corner of the navigation bar. Select "New repository".
When filling out the form for your new repo, you can make it public or private. Leave the "Add a README file", "Add .gitignore", and "Choose a license" checkboxes unchecked.
To push your existing code from your computer to GitHub, enter the following commands from your terminal:git remote add origin https://github.com/YOUR_GITHUB_USERNAME/YOUR_GITHUB_REPO_NAME.gitgit branch -M maingit push -u origin main
Build your site with Gatsby Cloud
Gatsby Cloud is a custom-built infrastructure platform that is specifically tailored to building and deploying Gatsby sites.
You can connect your codebase to Gatsby Cloud through GitHub:
Go to your Gatsby Cloud Dashboard. Click on the purple "Add a site" button next to the search bar.
The next few steps will help you go through the steps to create a new site. First, select "Import from a Git repository" and click the "Next" button at the bottom of the page.
Select GitHub as the Git provider.
Select your GitHub username from the "Select an Organization" dropdown.
If your username is listed in the dropdown, skip ahead to step 8.
If your username is not listed, choose "Add new Organization", which will open a new window with GitHub. The next few steps will show you how to give Gatsby Cloud access to your GitHub repo.
The new GitHub window will ask you where you want to install Gatsby Cloud. Find your username in the list of organizations, and click the corresponding "Configure" button.
GitHub will take you to the permissions page for Gatsby Cloud.
In the "Repository access" section, you can choose to give Gatsby Cloud access to all your repos or only select repos. To give access to select repos, use the "Select repositories" dropdown to find the name of the repo you created for your project. Don't forget to save your changes!
Now, when you go back to the Gatsby Cloud window, you should be able to find your repo using the "Select a Repository" field.
Once you select your repo, a few more options will show up, which you can use to configure the branch and display name that Gatsby Cloud will use for your site. You can leave the default settings and click the "Next" button.
Gatsby Cloud will ask you if you want to add any optional integrations to your site. For future projects, this might be useful if you want to use a CMS. But for now, click the "Skip this step" button.
Gatsby Cloud will also ask if you want to add any environment variables. Skip this section, and click the "Create site" button.
Now that your site has been created, you'll be taken to a site dashboard where you can see the status of your builds. Gatsby Cloud should start building your site automatically.
Every time you push a new change to the main branch of your GitHub repo, Gatsby Cloud will see the changes and automatically start a build for the new version of your site.
There will be a unique URL for each build (like
https://build-49535320-b3ae-4761-bbeb-f8f7fa07e0fc.gtsb.io/), and a URL that always has the latest build (like
Setting up Gatsby Hosting
Gatsby Cloud now includes hosting! That means that other people will be able to access your site using a URL that ends with
In order to use Gatsby Hosting, you first need to add the
gatsby-plugin-gatsby-cloud plugin to your site. (Don't worry about what this means for now. You'll learn more about plugins in a bit.)
- Run the following command from your terminal to install
gatsby-plugin-gatsby-cloud:npm install gatsby-plugin-gatsby-cloud
- Open up the
gatsby-config.jsfile at the root of your project. Update the
pluginsarray to look like this:plugins: [`gatsby-plugin-gatsby-cloud`,],
- Commit your changes and push them to your remote repository on GitHub:git add .git commit -m "Add plugin for hosting"git push
Then, you can set up Gatsby Hosting in your browser:
- Go to the Gatsby Cloud page for your site, then click into the "Site Settings" tab.
- Select "Hosting" from the sidebar.
- Find the "Deploy to Gatsby Hosting" section, and click the "Turn on" button.
Now you can access your site using the
.gatsbyjs.io URL listed under "Connected domains"!
Exercise #1: Create and deploy your first Gatsby site
Create a new Gatsby site, then build and host it with Gatsby Cloud.
When you're done, you should have a
.gatsbyjs.io URL to your site that you can share in the chat.
You'll learn more if you work through the exercise on your own.
But if you get stuck, here's one possible solution.
Challenge (Extra Credit)
If you have a custom domain you'd like to connect to your site, you can set it up in Gatsby Cloud by following the instructions in this doc: Adding a Custom Domain.
Now that you've created the skeleton for your site and deployed it to Gatsby Cloud, you have a link to your site that you can share with anyone!
In the next section, you'll learn how to customize the contents of your site using React.
Share Your Feedback!
You can help us improve this workshop by using this feedback form to tell us what you liked or didn't like about this part of the workshop.